WindowDefProcPtr

WindowDefProcPtr
Header:	MacWindows.h		Carbon status:	Supported

Defines a pointer to a window definition callback function. Your window definition callback function determines how a window looks and behaves.

typedef SInt32(* WindowDefProcPtr) (
    SInt16 varCode, 
    WindowRef window, 
    SInt16 message, 
    SInt32 param
);

You would declare your function like this if you were to name it MyWindowDefCallback:

SInt32 MyWindowDefCallback (
    SInt16 varCode, 
    WindowRef window, 
    SInt16 message, 
    SInt32 param
);

varCode: The window’s variation code.
window: A pointer to the window’s window structure.
message: A value indicating the task to be performed. The message parameter contains one of the values defined in “Window Definition Message Constants”. Other messages are reserved for internal use by the system. The list in the discussion section that follows explains each of these tasks in detail.
param: Data associated with the task specified by the message parameter. If the task requires no data, this parameter is ignored.

function result: Your window definition function should perform whatever task is specified by the message parameter and return a function result, if appropriate. If the task performed requires no result code, return 0.

DISCUSSION

Various Window Manager functions call a window definition function whenever they need to perform a window-dependent action, such as drawing the window on the screen. If you wish to define new, nonstandard windows for your application, you must write a window definition function and store it in a resource file as a resource of type 'WDEF'.

The Window Manager calls the Resource Manager to access your window definition function with the given resource ID; see “Window Definition IDs” for a description of how window definition IDs are derived from resource IDs and variation codes. You can define your own window variation codes so that you can use one 'WDEF' resource to handle several variations of the same general window.

The Resource Manager reads your window definition function into memory and returns a handle to it. The Window Manager stores this handle in the windowDefProc field of the window structure. Later, when it needs to perform an action on the window, the Window Manager calls the window definition function and passes it the variation code as a parameter.

Your window definition function is responsible for

drawing the window frame
reporting the region where mouse-down events occur
calculating the window’s structure region and content region
drawing the size box
resizing the window frame when the user drags the size box
reporting the window’s features or the location of a specific window region
performing any customized initialization or disposal tasks

The Window Manager defines the data type WindowDefUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr WindowDefUPP;

You typically use the NewWindowDefProc macro like this:

WindowDefUPP myWindowDefUPP;

myWindowDefUPP = NewWindowDefProc(MyWindow);

You typically use the CallWindowDefProc macro like this:

CallWindowDefProc(myWindowDefUPP, varCode, theWindow, message, param);

The message parameter contains a value specifying the task to be performed by your window definiton function. These tasks are:

Drawing the Window Frame

When the Window Manager passes wDraw in the message parameter, your window definition function should respond by drawing the window frame in the current graphics port (which is the Window Manager port). The window part code to be drawn will be passed in the param parameter of your window definition function.

Your window definition function should perform the following steps:

Change the current port from the WMgrPort to the WMgrCPort to allow the system to draw in the full range of RGB colors.
Update the pen attributes, text attributes, and bkPat fields in the WMgrCPort to the values of the corresponding fields in the WMgrPort. The Window Manager automatically transfers the vis and clip regions.

The parallelism of the WMgrPort and the WMgrCPort is maintained only by the window definition functions. All window definition functions that draw in the WMgrPort should follow the steps listed above even if the changed fields do not affect their operation.

You must make certain checks to determine exactly how to draw the frame. If the value of the visible field in the window structure is false, you should do nothing; otherwise, you should examine the param parameter and the status flags in the window structure:

If the value of param is 0, draw the entire window frame (including the size box, if your window definition function incorporates the size box into the frame).
If the value of param is 0 and the hilited field in the window structure is true, highlight the frame to show that the window is active.

If the value of the goAwayFlag field in the window structure is also true, draw a close box in the window frame.

If the value of the spareFlag field in the window structure is also true, draw a zoom box in the window frame.
If the value of the param parameter is wInGoAway, add highlighting to, or remove it from, the window’s close box.
If the value of the param parameter is wInZoom, add highlighting to, or remove it from, the window’s zoom box.
If the value of the param parameter is wInCollapseBox, add highlighting to, or remove it from, the window’s collapse box.

You need to maintain your own state flag to determine whether the close, zoom, or collapse box is to be drawn as highlighted. Typically, you clear this state flag whenever you draw the entire frame, and you set it before drawing whenever your application is called to draw just the close, zoom, or collapse box. If the flag is set, you draw the box in a highlighted state.

The window frame typically, but not necessarily, includes the window’s title, which should be displayed in the system font and system font size. The Window Manager port is already set to use the system font and system font size.

Nothing drawn outside the window’s structure region will be visible.

Your window definition function should return 0 as the function result for this message.

Reporting the Region of a Mouse-Down Event

When the Window Manager passes wHit in the message parameter, your window definition function should respond by reporting the region of the specified mouse-down event. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function. The vertical coordinate is in the high-order word of the parameter, and the horizontal coordinate is in the low-order word.

In response to the wHit message, your window definition function should return one of the constants defined in “Mouse-down Event Reporting Constants”.

Return the constants wInGrow, wInGoAway, wInZoomIn, wInZoomOut, and wInCollapseBox only if the window is active—by convention, the size box, close box, zoom box, and collapse box aren’t drawn if the window is inactive. In an inactive document window, for example, a mouse-down event in the part of the title bar that would contain the close box if the window were active is reported as wInDrag.

Calculating Regions

When the Window Manager passes wCalcRgns in the message parameter, your window definition function should respond by calculating the window’s structure and content regions based on the current graphics port’s port rectangle. These regions, whose handles are in the strucRgn and contRgn fields of the window structure, are in global coordinates. The Window Manager requests this operation only if the window is visible. The mouse location (in global coordinates) of the window frame will be passed into the param parameter of your window definition function.

Your window definition function should call IsWindowCollapsed to determine its collapse state. Then your window definition function can modify its structure and content regions as appropriate. Typically, a window’s content region is empty in a collapsed state.

When you calculate regions for your own type of window, do not alter the clip region or the visible region of the Window Manager port. The Window Manager and QuickDraw take care of this for you. Altering the Window Manager port’s clip region or visible region may damage other windows.

Your window definition function should return 0 as the function result for this message.

Performing Additional Window Initialization

When the Window Manager passes wNew in the message parameter, your window definition function should respond by performing any initialization that it may require. If the content region has an unusual shape, for example, you might allocate memory for the region and store the region handle in the dataHandle field of the window structure. The initialization function for a standard document window creates the wStateData structure for storing zooming data.

Your window definition function should ignore the param parameter and return 0 as the function result for this message.

Performing Additional Window Disposal Actions

When the Window Manager passes wDispose in the message parameter, your window definition function should respond by performing any additional tasks necessary for disposing of a window. You might, for example, release memory that was allocated by the initialization function. The dispose function for a standard document window disposes of the wStateData structure.

Your window definition function should ignore the param parameter and return 0 as the function result for this message.

Drawing the Window’s Grow Image

When the Window Manager passes wGrow in the message parameter, your window definition function should respond to being resized by drawing a dotted outline of the window in the current graphics port in the pen pattern and mode. (The pen pattern and mode are set up—as gray and notPatXor—to conform to Appearance-compliant human interface guidelines.)

A rectangle (in global coordinates) whose upper-left corner is aligned with the port rectangle of the window’s graphics port is passed into the param parameter of your window definition function. Your grow image should be sized appropriately for the specified rectangle. As the user drags the mouse, the Window Manager sends repeated wGrow messages, so that you can change your grow image to match the changing mouse location.

DrawGrowIcon draws a dotted (gray) outline of the window and also the lines delimiting the title bar, size box, and scroll bar areas.

Your window definition function should return 0 as the function result for this message.

Drawing the Size Box

When the Window Manager passes wDrawGIcon in the message parameter, your window definition function should respond by drawing the size box in the content region if the window is active. If the window is inactive, your window definition function should draw whatever is appropriate to show that the window cannot currently be sized. Your window definition function may also draw scroll bar delimiter lines. Your window definition function should ignore the param parameter.

If the size box is located in the window frame, draw the size box in response to a wDraw message, not a wDrawGIcon message.

Your window definition function should return 0 as the function result for this message.

Reporting Window Features

When the Window Manager passes kWindowMsgGetFeatures in the message parameter, your window definition function should respond by setting the param parameter to reflect the features that your window supports. The value passed back in the param parameter should be comprised of one or more of the values defined in “Window Feature Reporting Constants”.

Your window definition function should return 1 as the function result for this message.

Returning the Location of Window Regions

When the Window Manager passes kWindowMsgGetRegion in the message parameter, your window definition function should respond by returning the location (in global coordinates) of the specified window region. A pointer to a window region structure will be passed in the param parameter.

The window region structure is a structure of type GetWindowRegionRec. Your window definition function should return an operating system status (OSStatus) message as the function result for this message. The result code errWindowRgnInvalid indicates that the window region passed in was not valid.

Application-defined window definition functions are changed with Appearance Manager 1.0 to support collapse boxes and feature reporting.

AVAILABILITY

Supported in Carbon.